import { Tooltip as RadixTooltip, Button } from '@modulz/radix';
import ReachTooltip from '@reach/tooltip';

<article>

<Title>Tooltip</Title>

Tooltip is a non-interactive overlay that briefly explains the function of the trigger element.

<Icon icon="tooltip" />

> If you're looking for a simple tooltip, consider using the [HTML `title` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) instead.

</article>

<article>

## Functionality

- Displayed when the trigger element is hovered by the mouse or when it receives keyboard focus.
- Focus remains on the trigger element while the tooltip is displayed.
- Dismissed with the `Escape` key or by navigating outside.
- Has pre-defined positioning options, but should adjust itself dynamically based on collisions and available space.

</article>

<article>

## Best practices

- Do not use a tooltip for information vital to task completion. The action of the element it is attached to should make sense on its own.
- Make sure to provide a short and succinct label for the tooltip.
- Avoid interactive content such as buttons and links inside the tooltip. As an alternative, consider <Link href="/play/popover">Popover</Link>.
- Displaying the tooltip too quickly on mouseover can result in accidental activations and creates a jarring user experience.
  It is advisable to add a short delay (~100ms) before displaying it.
- Once a tooltip is visible, interaction with any other tooltip should display immediately without the delay.

</article>

<article>

## Implementation

### Positioning

To avoid parent containers possibly clipping the tooltip and its content, render the tooltip outside the DOM hierarchy of its parent component.

In React, a common mechanism for this is a [Portal](https://reactjs.org/docs/portals.html).

### Disabled elements

By default, [disabled elements like `<button>` do not trigger mouse events](https://jakearchibald.com/2017/events-and-disabled-form-fields/).

This is an unfortunate misinterpretation of the spec by the browsers. As a workaround, we recommend using [Pointer Events](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events)
(which follow the spec more closely) for disabled trigger elements.

As an alternative, wrapping the disabled element in a `<span>` can also work since all of the mouse events would then be placed on it instead.

</article>

<article>

## Examples

### [Reach UI — Tooltip (React)](https://reach.tech/tooltip/)

We recommend using Reach UI's tooltip as a base for your React based implementation.

<ReachTooltip label="Save">
  <button>💾</button>
</ReachTooltip>

<hr />

### [Modulz, Radix — Tooltip (React)](https://radix.modulz.app/docs/tooltip/)

<RadixTooltip label="You do not have permission to delete this user." side="top" align="center">
  <span style={{ display: 'inline-block' }}>
    <Button size={1} disabled>
      Delete user
    </Button>
  </span>
</RadixTooltip>

</article>

<article>

## Accessibility

The accessibility requirements for this component are defined by the [WAI-ARIA Practices for Tooltip](https://www.w3.org/TR/wai-aria-practices/#tooltip):

- [Keyboard Interaction](https://www.w3.org/TR/wai-aria-practices-1.1/#keyboard-interaction-21)
- [WAI-ARIA Roles, States, and Properties](https://www.w3.org/TR/wai-aria-practices-1.1/#wai-aria-roles-states-and-properties-22)

</article>

<article>

## Resources

- [WAI-ARIA Practices — Tooltip](https://www.w3.org/TR/wai-aria-practices/#tooltip)
- [Reach UI — Tooltip](https://reach.tech/tooltip/)
- [Shopify Polaris — Tooltip](https://polaris.shopify.com/components/overlays/tooltip)
- [Tooltips: How to use this small but mighty UI pattern correctly](https://www.appcues.com/blog/tooltips)
- [Events and disabled form fields](https://jakearchibald.com/2017/events-and-disabled-form-fields/)
- [Timing Guidelines for Exposing Hidden Content](https://www.nngroup.com/articles/timing-exposing-content/)

</article>
